package com.googlecode.gaal.data.api;

/**
 * An int sequence similar to the CharSequence allowing reversal
 * 
 * @author alex
 * @see CharSequence
 */
public interface IntSequence extends Comparable<IntSequence> {
    /**
     * @param index
     *            an index of an element
     * @param defaultValue
     *            the default value returned in case the index is not in the
     *            sequence
     * @return an element at index start+index for a forward sequence or
     *         (size()-index+1) for a reverse sequence, in case the index is out
     *         of bounds zero is returned
     */
    int get(int index, int defaultValue);

    /**
     * @param index
     *            an index of an element
     * @return same as get, but an exception is thrown if the index is out of
     *         bounds
     * @throws IndexOutOfBoundsException
     *             if the index is out of bounds
     */
    int get(int index) throws IndexOutOfBoundsException;

    /**
     * @return the sequence length
     */
    int size();

    /**
     * Returns a new Sequence that is a subsequence from start to end -1 of this
     * sequence. The length of this sequence is end - start
     * 
     * @param start
     *            the start index, inclusive
     * @param end
     *            the end index, exclusive
     * @return the specified subsequence
     * @throws IndexOutOfBoundsException
     *             if start is negative, if end is greater than size(), or if
     *             end is smaller than start
     */
    IntSequence subSequence(int start, int end) throws IndexOutOfBoundsException;

    /**
     * @return a new sequence representing a reverse of the current sequence
     */
    IntSequence reverse();
}
